home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / blitzbasic / riblitzlibs.lha / riblitzlibs / pack / Pack_Library.DOC < prev    next >
Text File  |  2002-02-02  |  7KB  |  170 lines
  1. PACK Library v0.1
  2. =================
  3.  
  4. By Stephen McNamara with a little help from Steve Matty
  5. (c)1994 Reflective Images
  6.  
  7. This library contains commands for the unpacking of ILBM's (IFF pictures)
  8. and the grabbing of their palettes (CMAP chunks).  Nearly all the commands
  9. in this library can be used as either STATEMENTS or FUNCTIONS.  Usage is
  10. identical in both cases but if used as a function then the command will
  11. return:
  12.         FALSE for failure
  13.         TRUE for success
  14.  
  15. Please feel free to critisise (or praise!) this library, send me anything
  16. you want to say about it at:
  17.  
  18.             Stephen McNamara,
  19.               17 Mayles Road,
  20.                     Southsea,
  21.                   Portsmouth,
  22.                    Hampshire,
  23.                      England.
  24.                      PO4 8NP.
  25.     Telephone: (England) 0705 781507.
  26.  
  27. Or send us anything you've written........
  28.  
  29.  
  30. Command list:
  31.             UnpackIFF address.l,bitmap#[,lines]
  32.             suc=UnpackIFF (address.l,bitmap#[,lines])
  33.             ILBMPalette address.l,palette#
  34.             suc=ILBMPalette (address.l,palette#)
  35.             ILBMGrab address.l,bitmap#,palette#
  36.             LoadIFF filename$,bitmap#[,palette#]
  37.             suc=LoadIFF (filename$,bitmap#[,palette#])
  38.             DeIce source_address,dest_address
  39.             suc=DeIce (source_address,dest_address)
  40.             val.l=ChunkHeader (A$)
  41.  
  42. Statement/Function: UnpackIFF
  43. ------------------------------------------------------------------------
  44. Modes : Amiga/Blitz
  45. Syntax: UnpackIFF address.l,bitmap#[,lines]
  46.     suc=UnpackIFF (address.l,bitmap#[,lines])
  47.  
  48.   This command is used to unpack an IFF picture file from memory onto a
  49. bitmap.  Address.l should point to the START of the iff file header in
  50. memory (either CHIP or FAST mem can be used), bitmap should be the number
  51. of a previously initialised bitmap.  The optional lines parameter allows
  52. you to specify the number of lines to unpack from the IFF file.
  53.   This command checks the size of the bitmap against the size of the IFF
  54. before it unpacks the IFF onto it.  Checks are made for width, height and
  55. depth of the bitmap and the IFF and the following is done:
  56.  
  57. (size=WIDTH, HEIGHT and DEPTH)
  58.  
  59.         BITMAP 'size' < IFF 'size' : unpack aborted
  60.         BITMAP 'size' = IFF 'size' : pic is unpacked
  61.         BITMAP 'size' > IFF 'size' : pic is unpacked
  62.  
  63.   Extra aborts can be caused by:
  64.         - not using a previously installed bitmap
  65.         - given the optional lines parameter as 0 or less
  66.         - not giving ADDRESS.l as a pointer to a valid IFF ILBM
  67.           header
  68.  
  69.   When using the optional parameter, you should note that if you try to
  70. unpack more lines than the IFF has, the unpack routine will automatically
  71. stop at the last line of the IFF.  It will not reject the UnpackIFF
  72. command.
  73.  
  74.   NOTE: you should save your IFF pictures with the STENCIL OFF because at
  75. the moment this routine does not check to see if STENCIL data is present in
  76. the IFF file.
  77.  
  78. Statement/Function: ILBMPalette
  79. ------------------------------------------------------------------------
  80. Modes : Amiga/Blitz
  81. Syntax: ILBMPalette address.l,palette#
  82.     suc=ILBMPalette (address.l,palette#)
  83.  
  84.   This command is used to grab the palette from a IFF picture file held in
  85. memory (CHIP or FAST mem).  Address.l should be given as the address of
  86. either an IFF file in memory or a CMAP chunk in memory.  When you use the
  87. SAVE PALETTE command from inside an art program (e.g. DPaint) or from
  88. inside Blitz2, the program saves out a CMAP chunk which gives details
  89. about the palette.  The CMAP chunk is also saved with IFF picture files to
  90. give the palette of the picture.
  91.   This command will look at the address you gave and try and find a CMAP
  92. chunk from the address given to address+5120.  If it finds a chunk it will
  93. grab the palette into the given palette object.  If the palette object
  94. already contains palette information then this information is deleted.
  95. This routine looks in the CMAP chunk and reserves the palette object to
  96. have the same number of colour entries.
  97.   This command will fail if it doesn't find a CMAP chunk.
  98.  
  99.  
  100. Statment: ILBMGrab
  101. ------------------------------------------------------------------------
  102. Modes : Amiga/Blitz
  103. Syntax: ILBMGrab address.l,bitmap#,palette#
  104.  
  105.   This command lets you grab both the palette and the graphics from an IFF
  106. picture file with just one command.  It returns to success parameter to
  107. say whether or not it succeeded in grabbing the data, so if you need to know
  108. if the grabbing was successful you'll have to use the separate commands
  109. for grabbing palettes and graphics.
  110.  
  111.   NOTE: this command essentially just calls both UnpackIFF and ILBMPalette
  112. so everything said about these commands is relevent for ILBMGrab.
  113.  
  114.  
  115. Statment/Function: LoadIFF
  116. ------------------------------------------------------------------------
  117. Modes : Amiga
  118. Syntax: LoadIFF filename$,bitmap#[,palette#]
  119.     suc=LoadIFF (filename$,bitmap#[,palette#])
  120.  
  121.   This command is a direct replacement for Blitz2's LoadBitmap.  It is a
  122. lot faster than Blitz's command since it loads the file into memory and
  123. then unpacks it from there.  Thus you need to ensure that you have enough
  124. free memory to load the IFF into before trying to use this command.
  125.   This command is also more stable than Blitz's since it checks for the
  126. existence of the file before trying to load it in.
  127.   The optional parameter allows you to load in the palette of the IFF
  128. picture.  Refer to UnpackIFF and ILBMPalette for more information about
  129. unpacking the graphics and grabbing the palettes.
  130.  
  131. IMPORTANT NOTE: to use this command you must have our FUNC library
  132. installed in your copy of Blitz2.  Use of this command without this library
  133. will probably lead to a bad crash of your Amiga!
  134.  
  135. Statement/Function: DeIce
  136. ------------------------------------------------------------------------
  137. Modes : Amiga
  138. Syntax: DeIce source_address,dest_address
  139.     suc=DeIce (source_address,dest_address)
  140.  
  141.   This is a command from my (Stephen McNamara) past.
  142.   It is used to unpack data files packed by my favourite Atari ST packer -
  143. PACK ICE v2.40.  I've put it into Blitz because still have loads of files
  144. that I've packed with it.  To use it, source_address should (obviously)
  145. contain the address of the data, dest_address should be where to unpack the
  146. data to.  In the function form, this command returns either 0 for unpack
  147. failed or -1 for success.
  148.   Note: The size of the data unpacked is the long word at source_address+8
  149. (I think, or is it 4?) if anybody is interested......
  150.  
  151.  
  152. Function: ChunkHeader
  153. ------------------------------------------------------------------------
  154. Modes : Amiga
  155. Syntax: val.l=ChunkHeader (A$)
  156.  
  157.   This command was put in by me (Stephen McNamara) before I realised Blitz
  158. already had a command that does exactly the same.  I've left it in just
  159. because I want to.  It is useful when looking through IFF files for chunks
  160. (e.g. ILBM, CMAP, etc.) as it gives you a longword value to look for in
  161. memory to find the chunk.  The string should be a four character string
  162. (e.g. CMAP), you'll be returned the longword value of the string.
  163.   This command does the job of the following bit of Blitz2 code:
  164.  
  165.         a$="CMAP"
  166.         val.l=Peek.l(&a$)
  167.  
  168.  
  169. >> END
  170.